/*
 * This file is part of WebCL – JavaScript bindings for OpenCL
 * http://webcl.nokiaresearch.com/
 *
 * Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
 *
 * Contact: Jari Nikara  ;jari.nikara@nokia.com;
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * version 2.1 as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 *
 * The package is based on a published Khronos OpenCL 1.1 Specification,
 * see http://www.khronos.org/opencl/.
 *
 * OpenCL is a trademark of Apple Inc.
 */

/** \interface IWebCLCommandQueue
 * IWebCLCommandQueue interface abstracts a WebCL command queue.
 * \see cl_command_queue
 */

#include "nsISupports.idl"
#include "nsISecurityCheckedComponent.idl"
#include "nsIVariant.idl"

#include "WebCL_types.idl"

interface IWebCLEvent;
interface IWebCLKernel;
interface IWebCLMemoryObject;

[scriptable, uuid(751b06c0-cac3-4123-87ae-2b8c22832d52)]
interface IWebCLCommandQueue : nsISecurityCheckedComponent
{
  /** Get command queue info.
   * \param aName Name of the info parameter.
   * \return The resulting value.
   * \see clGetCommandQueueInfo
   * \see WebCL_types
   */
  [implicit_jscontext]
  nsIVariant getCommandQueueInfo (in long aName);

  /** Enqueues a command to execute a kernel on a device.
   * \param aKernel A WebCLKernel instance.
   * \param aWorkDim The number of dimensions used to specify the global
   *  work-items and work-items in the work-group.
   * \param aGlobalWorkOffset Array of aWorkDim integers that describe
   *  the offset used to calculate the global ID of a work-item.
   * \param aGlobalWorkSize Array of aWorkDim integers that describe
   *  the number of global work-items in work_dim dimensions that
   *  will execute the kernel function.
   * \param aLocalWorkSize Array of aWorkDim integers that describe
   *  the number of work-items that make up a work-group that will
   *  execute the kernel specified by kernel.
   * \param aEventWaitList Optional array of IWebCLEvents that need
   *  to complete before this particular command can be executed.
   * \return A WebCLEvent instance that identifies this particular
   *  kernel execution instance
   * \see clEnqueueNDRangeKernel
   */
  [implicit_jscontext]
  IWebCLEvent enqueueNDRangeKernel (in nsISupports aKernel,
                                    in unsigned long aWorkDim,
                                    in nsIVariant aGlobalWorkOffset,
                                    in nsIVariant aGlobalWorkSize,
                                    in nsIVariant aLocalWorkSize,
                                    [optional] in nsIVariant aEventWaitList);

  /** Enqueues a command to execute a kernel on a device.
   * \param aKernel A WebCLKernel instance.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular
   *  kernel execution instance
   * \see clEnqueueTask
   */
  [implicit_jscontext]
  IWebCLEvent enqueueTask (in nsISupports aKernel,
                           [optional] in nsIVariant aEventWaitList);

  /** Enqueue commands to write to a buffer object from host memory.
   * \param aBuffer A WebCLMemoryObject instance created as a buffer.
   * \param aBlockingWrite Indicates if the write operations are
   *  blocking or nonblocking.
   * \param aOffset The offset in bytes in the buffer object to write to.
   * \param aSize The size in bytes of data being written.
   * \param aData A TypedArray instance from which the data is
   *  to be written from. The buffer size must be at least \c aSize bytes.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueWriteBuffer
   */
  [implicit_jscontext]
  IWebCLEvent enqueueWriteBuffer (in nsISupports aBuffer,
                                  in boolean aBlockingWrite,
                                  in T_WebCLSize aOffset,
                                  in T_WebCLSize aSize,
                                  in nsIVariant aData,
                                  [optional] in nsIVariant aEventWaitList);

  /** Enqueue commands to read from a buffer object to host memory.
   * \param aBuffer A WebCLMemoryObject instance created as a buffer.
   * \param aBlockingRead Indicates if the read operations are
   *  blocking or nonblocking.
   * \param aOffset The offset in bytes in the buffer object to read from.
   * \param aSize The size in bytes of data being read.
   * \param aData A TypedArray instance to which the data is
   *  to be read to. The buffer size must be at least \c aSize bytes.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueReadBuffer
   */
  [implicit_jscontext]
  IWebCLEvent enqueueReadBuffer (in nsISupports aBuffer,
                                 in boolean aBlockingRead,
                                 in T_WebCLSize aOffset,
                                 in T_WebCLSize aSize,
                                 in nsIVariant aData,
                                 [optional] in nsIVariant aEventWaitList);

  /** Enqueue commands to write a rectangular region to a buffer object
   * from host memory.
   * \param aBuffer A WebCLMemoryObject instance created as a buffer.
   * \param aBlockingWrite Indicates if the write operations are
   *  blocking or nonblocking.
   * \param aBufferOrigin Array of 3 integers.
   * \param aHostOrigin Array of 3 integers.
   * \param aRegion Array of 3 integers.
   * \param aBufferRowPitch
   * \param aBufferSlicePitch
   * \param aHostRowPitch
   * \param aHostSlicePitch
   * \param aData A TypedArray instance from which the data is
   *  to be written from. A large enough buffer must be allocated.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueWriteBufferRect
   */
  [implicit_jscontext]
  IWebCLEvent enqueueWriteBufferRect (in nsISupports aBuffer,
                                      in boolean aBlockingWrite,
                                      in nsIVariant aBufferOrigin,
                                      in nsIVariant aHostOrigin,
                                      in nsIVariant aRegion,
                                      in T_WebCLSize aBufferRowPitch,
                                      in T_WebCLSize aBufferSlicePitch,
                                      in T_WebCLSize aHostRowPitch,
                                      in T_WebCLSize aHostSlicePitch,
                                      in nsIVariant aData,
                                      [optional] in nsIVariant aEventWaitList);

  /** Enqueue commands to read from a rectangular region from a buffer
   * object to host memory.
   * \param aBuffer A WebCLMemoryObject instance created as a buffer.
   * \param aBlockingRead Indicates if the read operations are
   *  blocking or nonblocking.
   * \param aBufferOrigin Array of 3 integers.
   * \param aHostOrigin Array of 3 integers.
   * \param aRegion Array of 3 integers.
   * \param aBufferRowPitch
   * \param aBufferSlicePitch
   * \param aHostRowPitch
   * \param aHostSlicePitch
   * \param aData A TypedArray instance to which the data is
   *  to be read to. A large enough buffer must be allocated.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueReadBufferRect
   */
  [implicit_jscontext]
  IWebCLEvent enqueueReadBufferRect (in nsISupports aBuffer,
                                     in boolean aBlockingRead,
                                     in nsIVariant aBufferOrigin,
                                     in nsIVariant aHostOrigin,
                                     in nsIVariant aRegion,
                                     in T_WebCLSize aBufferRowPitch,
                                     in T_WebCLSize aBufferSlicePitch,
                                     in T_WebCLSize aHostRowPitch,
                                     in T_WebCLSize aHostSlicePitch,
                                     in nsIVariant aData,
                                     [optional] in nsIVariant aEventWaitList);

  /** Enqueues a command to write to a 2D or 3D image object from host memory.
   * \param aImage A WebCLMemoryObject instance created as an image.
   * \param aBlockingWrite Indicates if the write operations are
   *  blocking or nonblocking.
   * \param aOrigin Array of 3 integers.
   * \param aRegion Array of 3 integers.
   * \param aInputRowPitch
   * \param aInputSlicePitch
   * \param aData A TypedArray instance from which the data is
   *  to be written from. A large enough buffer must be allocated.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueWriteImage
   */
  [implicit_jscontext]
  IWebCLEvent enqueueWriteImage (in nsISupports aImage,
                                 in boolean aBlockingWrite,
                                 in nsIVariant aOrigin,
                                 in nsIVariant aRegion,
                                 in T_WebCLSize aInputRowPitch,
                                 in T_WebCLSize aInputSlicePitch,
                                 in nsIVariant aData,
                                 [optional] in nsIVariant aEventWaitList);

  /** Enqueues a command to read from a 2D or 3D image object to host memory.
   * \param aImage A WebCLMemoryObject instance created as an image.
   * \param aBlockingRead Indicates if the read operations are
   *  blocking or nonblocking.
   * \param aOrigin Array of 3 integers.
   * \param aRegion Array of 3 integers.
   * \param aRowPitch
   * \param aSlicePitch
   * \param aData A TypedArray instance to which the data is
   *  to be read to. A large enough buffer must be allocated.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueReadImage
   */
  [implicit_jscontext]
  IWebCLEvent enqueueReadImage (in nsISupports aImage,
                                in boolean aBlockingRead,
                                in nsIVariant aOrigin,
                                in nsIVariant aRegion,
                                in T_WebCLSize aRowPitch,
                                in T_WebCLSize aSlicePitch,
                                in nsIVariant aData,
                                [optional] in nsIVariant aEventWaitList);

  /** Enqueues a command to copy image objects.
   * \param aSrcImage Source image, a WebCLMemoryObject instance created
   *  as an image.
   * \param aDstImage Destination image, a WebCLMemoryObject instance
   *  created as an image.
   * \param aSrcOrigin Array of 3 integers.
   * \param aDstOrigin Array of 3 integers.
   * \param aRegion Array of 3 integers.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueCopyImage
   */
  [implicit_jscontext]
  IWebCLEvent enqueueCopyImage (in nsISupports aSrcImage,
                                in nsISupports aDstImage,
                                in nsIVariant aSrcOrigin,
                                in nsIVariant aDstOrigin,
                                in nsIVariant aRegion,
                                [optional] in nsIVariant aEventWaitList);

  /** Enqueues a command to copy an image object to a buffer object.
   * \param aSrcImage Source image, a WebCLMemoryObject instance created
   *  as an image.
   * \param aDstBuffer Destination buffer, a WebCLMemoryObject instance
   *  created as a buffer.
   * \param aSrcOrigin Array of 3 integers.
   * \param aRegion Array of 3 integers.
   * \param aDstOffset The offset where to begin copying data into aDstBuffer.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueCopyImageToBuffer
   */
  [implicit_jscontext]
  IWebCLEvent enqueueCopyImageToBuffer (in nsISupports aSrcImage,
                                        in nsISupports aDstBuffer,
                                        in nsIVariant aSrcOrigin,
                                        in nsIVariant aRegion,
                                        in T_WebCLSize aDstOffset,
                                        [optional] in nsIVariant aEventWaitList);

  /** Enqueues a command to copy a buffer object to an image object.
   * \param aSrcBuffer Source buffer, a WebCLMemoryObject instance
   *  created as a buffer.
   * \param aDstImage Destination image, a WebCLMemoryObject
   *  instance created as an image.
   * \param aSrcOffset The offset where to begin copying data from aSrcBuffer.
   * \param aDstOrigin Array of 3 integers.
   * \param aRegion Array of 3 integers.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueCopyBufferToImage
   */
  [implicit_jscontext]
  IWebCLEvent enqueueCopyBufferToImage (in nsISupports aSrcBuffer,
                                        in nsISupports aDstImage,
                                        in T_WebCLSize aSrcOffset,
                                        in nsIVariant aDstOrigin,
                                        in nsIVariant aRegion,
                                        [optional] in nsIVariant aEventWaitList);

  /** Enqueues a command to map a region of the buffer object given by aBuffer
   * into the host address space represented by aData. NOT IMPLEMENTED
   * \param aBuffer A WebCLMemoryObject instance created as a buffer.
   * \param aBlockingMap Indicates if the map operation is blocking
   *  or non-blocking.
   * \param aMapFlags A bit field of valid mapping flags (CL_MAP_READ,
   *  CL_MAP_WRITE).
   * \param aOffset The offset in bytes of the region in the buffer
   *  object that is being mapped.
   * \param aSize The size in bytes of the region in the buffer
   *  object that is being mapped.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \param aData The TypedArray into which the buffer is to be mapped.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueMapBuffer
   */
  [implicit_jscontext]
  IWebCLEvent enqueueMapBuffer (in nsISupports aBuffer,
                                in boolean aBlockingMap,
                                in T_WebCLMapFlags aMapFlags,
                                in T_WebCLSize aOffset,
                                in T_WebCLSize aSize,
                                in nsIVariant aEventWaitList,
                                in nsIVariant aData);

  /** Enqueues a command to map a region of an image object given by aImage
   * into the host address space represented by aData. NOT IMPLEMENTED
   * \param aImage A WebCLMemoryObject instance created as an image.
   * \param aBlockingMap Indicates if the map operation is blocking
   *  or non-blocking.
   * \param aMapFlags A bit field of valid mapping flags (CL_MAP_READ,
   *  CL_MAP_WRITE).
   * \param aOrigin The offset (x, y, z) in pixels of the 2D or 3D
   *  rectangle region that is to be mapped. Array of 3 integers.
   * \param aRegion The region (width, height, depth) in pixels of
   *  the 2D or 3D rectangle region that is to be mapped.
   *  Array of 3 integers.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \param aData The TypedArray into which the image is to be mapped.
   * \see clEnqueueMapImage
   */
  [implicit_jscontext]
  IWebCLEvent enqueueMapImage (in nsISupports aImage,
                               in boolean aBlockingMap,
                               in T_WebCLMapFlags aMapFlags,
                               in nsIVariant aOrigin,
                               in nsIVariant aRegion,
                               in nsIVariant aEventWaitList,
                               in nsIVariant aData);

  /** Enqueues a command to unmap a previously mapped region of
   * a memory object. NOT IMPLEMENTED
   * \param aMemObject A WebCLMemoryObject instance.
   * \param aMappedData A TypedArray instance returned by a previous
   *  call to enqueueMapBuffer or enqueueMapImage.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \return A WebCLEvent instance that identifies this particular command.
   * \see clEnqueueUnmapMemObject
   */
  [implicit_jscontext]
  IWebCLEvent enqueueUnmapMemObject (in nsISupports aMemObject,
                                     in nsIVariant aMappedData,
                                     [optional] in nsIVariant aEventWaitList);

  /** Enqueues a marker command.
   * \return A WebCLEvent instance that identifies the enqueued marker.
   * \see clEnqueueMarker
   */
  [implicit_jscontext]
  IWebCLEvent enqueueMarker ();

  /** Enqueues a command to wait for a specific event or a list of events
   * to complete before any future commands queued in the command-queue
   * are executed.
   * \param aEventWaitList Optional array of IWebCLEvents.
   * \see clEnqueueWaitForEvents
   */
  [implicit_jscontext]
  void enqueueWaitForEvents (in nsIVariant aEventWaitList);

  /** A synchronization point that enqueues a barrier operation.
   * \see clEnqueueBarrier
   */
  [implicit_jscontext]
  void enqueueBarrier ();

  /** Issues all previously queued commands in a command queue to the
   * device associated with the command-queue.
   * \see clFlush
   */
  [implicit_jscontext]
  void flush ();

  /** Blocks until all previously queued commands in a command queue are
   * issued to the associated device and have completed.
   * \see clFinish
   */
  [implicit_jscontext]
  void finish ();

  /** Immediately releases all OpenCL-related resources if any are allocated
   * for this object. The object should not be used anymore after calling
   * this function.
   */
  void releaseCLResources ();
};
